package suprax

// =============================================================================
// THROUGHPUT BUDGET - The Foundation of v20
// =============================================================================

// Every component must support this throughput without artificial bottlenecks.
// The key insight: match backend to realistic frontend delivery, not peak.

type ThroughputBudget struct {
    // Frontend can deliver 12 bundles/cycle, but not all are full:
    // - NOP bundles: ~5% (compiler padding)
    // - Partial bundles: ~15% (branches, taken paths)
    // - Full bundles: ~80%
    
    // Effective ops delivered:
    // 12 bundles × (0.05×0 + 0.15×2 + 0.80×4) = 12 × 3.56 = 42.7 ops/cycle
    
    // Round to 40 ops/cycle as our design target (with headroom)
}

const (
    // Frontend
    FetchBundlesPerCycle  = 12   // Peak bundle fetch
    EffectiveOpsPerBundle = 3.5  // Average (accounting for NOPs, partials)
    EffectiveOpsPerCycle  = 42   // 12 × 3.5, rounded
    
    // Backend Target (with 5% headroom)
    RenameWidth           = 44   // Can rename 44 µops/cycle
    IssueWidth            = 48   // Can issue 48 ops/cycle (burst handling)
    CommitWidth           = 44   // Can commit 44 µops/cycle
    
    // Execution (1.25× sustained demand for burst handling)
    ExecutionSlots        = 52   // 42 × 1.25 ≈ 52 execution slots
    
    // This is more efficient than v18-R's 68 units!
)

// WorkloadAnalysis derives unit counts from SPEC-like workload profiles
type WorkloadAnalysis struct {
    // Instruction mix (from published SPEC2017 analysis):
    IntegerALU    float64 // 42% - ADD, SUB, logic, shifts
    Memory        float64 // 25% - loads dominate modern code
    Branch        float64 // 12% - 1 branch per ~8 instructions
    IntegerMul    float64 // 8%  - more common than assumed
    FloatingPoint float64 // 10% - varies wildly by workload
    IntegerDiv    float64 // 1%  - rare
    Other         float64 // 2%  - misc (moves, NOPs, etc.)
}

var DefaultWorkload = WorkloadAnalysis{
    IntegerALU:    0.42,
    Memory:        0.25,
    Branch:        0.12,
    IntegerMul:    0.08,
    FloatingPoint: 0.10,
    IntegerDiv:    0.01,
    Other:         0.02,
}

// DeriveUnitCounts calculates execution unit requirements
func (w WorkloadAnalysis) DeriveUnitCounts(opsPerCycle int, overprovision float64) map[string]int {
    base := float64(opsPerCycle)
    
    return map[string]int{
        "ALU": int(math.Ceil(base * w.IntegerALU * overprovision)),      // 42 × 0.42 × 1.25 = 22
        "LSU": int(math.Ceil(base * w.Memory * overprovision)),          // 42 × 0.25 × 1.25 = 14
        "BRU": int(math.Ceil(base * w.Branch * overprovision)),          // 42 × 0.12 × 1.25 = 7
        "MUL": int(math.Ceil(base * w.IntegerMul * overprovision)),      // 42 × 0.08 × 1.25 = 5
        "FPU": int(math.Ceil(base * w.FloatingPoint * overprovision)),   // 42 × 0.10 × 1.25 = 6
        "DIV": 2, // Minimum 2 for latency hiding (18-cycle latency)
    }
}

// Result: 22 ALU + 14 LSU + 7 BRU + 5 MUL + 6 FPU + 2 DIV = 56 units
// This is between v18 (36) and v18-R (68) - properly balanced!

package suprax

// =============================================================================
// L1 INSTRUCTION CACHE - Cycle-Accurate Model
// =============================================================================

const (
    L1I_Size          = 32 * 1024  // 32 KB
    L1I_LineSize      = 64         // bytes per line
    L1I_Ways          = 4          // 4-way set-associative
    L1I_Banks         = 4          // 4 parallel banks
    L1I_Sets          = L1I_Size / (L1I_LineSize * L1I_Ways)  // 128 sets
    L1I_SetsPerBank   = L1I_Sets / L1I_Banks                  // 32 sets per bank
    L1I_TagBits       = 50         // bits [63:14] for 64-bit address
    L1I_IndexBits     = 7          // bits [13:7] for set selection
    L1I_BankBits      = 2          // bits [6:5] for bank selection
    L1I_OffsetBits    = 5          // bits [4:0] for byte within line
)

// L1ICacheLine represents a single cache line
type L1ICacheLine struct {
    Valid bool
    Tag   uint64
    Data  [L1I_LineSize]byte
    // No dirty bit needed - I-cache is read-only
}

// L1ICacheSet represents one set (4 ways)
type L1ICacheSet struct {
    Lines [L1I_Ways]L1ICacheLine
    LRU   uint8  // 3-bit pseudo-LRU for 4 ways
}

// L1ICacheBank represents one bank (32 sets)
type L1ICacheBank struct {
    Sets [L1I_SetsPerBank]L1ICacheSet
}

// L1ICache is the complete instruction cache
type L1ICache struct {
    Banks           [L1I_Banks]L1ICacheBank
    WayPredictor    [L1I_Sets]uint8  // 2 bits per set: predicted way
    
    // Pipeline state
    Stage1_PC       uint64
    Stage1_Valid    bool
    Stage2_Data     [192]byte  // 12 bundles worth
    Stage2_Hit      bool
    Stage2_Way      int
    
    Stats           L1ICacheStats
}

type L1ICacheStats struct {
    Accesses        uint64
    Hits            uint64
    WayPredictHits  uint64
    Misses          uint64
}

// NewL1ICache creates and initializes a new instruction cache
func NewL1ICache() *L1ICache {
    return &L1ICache{}  // All fields zero-initialized (invalid lines)
}

// AddressToIndices extracts cache indices from a PC
func (c *L1ICache) AddressToIndices(pc uint64) (bank, set int, tag uint64) {
    bank = int((pc >> 5) & 0x3)         // bits [6:5]
    set = int((pc >> 7) & 0x7F)         // bits [13:7] 
    tag = pc >> 14                       // bits [63:14]
    return
}

// Access performs a cache access (called each cycle)
// Returns: data slice, hit status, latency (1 or 2 cycles)
func (c *L1ICache) Access(pc uint64) (data []byte, hit bool, latency int) {
    c.Stats.Accesses++
    
    bank, setIdx, tag := c.AddressToIndices(pc)
    globalSetIdx := bank*L1I_SetsPerBank + (setIdx % L1I_SetsPerBank)
    set := &c.Banks[bank].Sets[setIdx % L1I_SetsPerBank]
    
    // Way prediction check (parallel with tag compare)
    predictedWay := c.WayPredictor[globalSetIdx] & 0x3
    
    // Check predicted way first
    if set.Lines[predictedWay].Valid && set.Lines[predictedWay].Tag == tag {
        c.Stats.Hits++
        c.Stats.WayPredictHits++
        c.updateLRU(set, int(predictedWay))
        return set.Lines[predictedWay].Data[:], true, 1  // Fast path: 1 cycle
    }
    
    // Check other ways (this adds 1 cycle)
    for way := 0; way < L1I_Ways; way++ {
        if way == int(predictedWay) {
            continue  // Already checked
        }
        if set.Lines[way].Valid && set.Lines[way].Tag == tag {
            c.Stats.Hits++
            c.updateLRU(set, way)
            // Update way predictor for next time
            c.WayPredictor[globalSetIdx] = uint8(way)
            return set.Lines[way].Data[:], true, 2  // Slow path: 2 cycles
        }
    }
    
    // Miss
    c.Stats.Misses++
    return nil, false, 0
}

// updateLRU updates the pseudo-LRU bits for a 4-way set
// Uses tree-based pseudo-LRU: 3 bits encode MRU path
func (c *L1ICache) updateLRU(set *L1ICacheSet, accessedWay int) {
    // Tree structure:
    //        [2]
    //       /   \
    //     [1]   [0]
    //    /  \   /  \
    //   W0  W1 W2  W3
    //
    // Bit points toward LRU subtree
    
    switch accessedWay {
    case 0:
        set.LRU = (set.LRU | 0x4) | 0x2  // Set bits 2 and 1
    case 1:
        set.LRU = (set.LRU | 0x4) & ^uint8(0x2)  // Set bit 2, clear bit 1
    case 2:
        set.LRU = (set.LRU & ^uint8(0x4)) | 0x1  // Clear bit 2, set bit 0
    case 3:
        set.LRU = (set.LRU & ^uint8(0x4)) & ^uint8(0x1)  // Clear bits 2 and 0
    }
}

// GetLRUWay returns the LRU way for replacement
func (c *L1ICache) GetLRUWay(set *L1ICacheSet) int {
    // Navigate tree based on LRU bits
    if set.LRU&0x4 == 0 {  // Go left (ways 0-1)
        if set.LRU&0x2 == 0 {
            return 0
        }
        return 1
    }
    // Go right (ways 2-3)
    if set.LRU&0x1 == 0 {
        return 2
    }
    return 3
}

// Fill handles a cache fill from L2
func (c *L1ICache) Fill(pc uint64, data []byte) {
    bank, setIdx, tag := c.AddressToIndices(pc)
    set := &c.Banks[bank].Sets[setIdx % L1I_SetsPerBank]
    
    // Find victim using LRU
    victimWay := c.GetLRUWay(set)
    
    // Install new line
    set.Lines[victimWay].Valid = true
    set.Lines[victimWay].Tag = tag
    copy(set.Lines[victimWay].Data[:], data)
    
    // Update way predictor
    globalSetIdx := bank*L1I_SetsPerBank + (setIdx % L1I_SetsPerBank)
    c.WayPredictor[globalSetIdx] = uint8(victimWay)
    
    c.updateLRU(set, victimWay)
}

// Invalidate removes a line from the cache (for coherency)
func (c *L1ICache) Invalidate(pc uint64) {
    bank, setIdx, tag := c.AddressToIndices(pc)
    set := &c.Banks[bank].Sets[setIdx % L1I_SetsPerBank]
    
    for way := 0; way < L1I_Ways; way++ {
        if set.Lines[way].Valid && set.Lines[way].Tag == tag {
            set.Lines[way].Valid = false
            return
        }
    }
}

// GetHitRate returns the current hit rate
func (c *L1ICache) GetHitRate() float64 {
    if c.Stats.Accesses == 0 {
        return 0
    }
    return float64(c.Stats.Hits) / float64(c.Stats.Accesses)
}

// GetWayPredictAccuracy returns way prediction accuracy
func (c *L1ICache) GetWayPredictAccuracy() float64 {
    if c.Stats.Hits == 0 {
        return 0
    }
    return float64(c.Stats.WayPredictHits) / float64(c.Stats.Hits)
}

package suprax

// =============================================================================
// TAGE-SC-L BRANCH PREDICTOR - Cycle-Accurate Model
// =============================================================================

const (
    // TAGE Configuration
    TAGE_NumTables     = 6                          // Tables T1-T6
    TAGE_BaseTableSize = 4096                       // Bimodal base predictor
    TAGE_TableSize     = 1024                       // Entries per TAGE table
    TAGE_TagBits       = 10                         // Partial tag bits
    TAGE_CounterBits   = 3                          // Signed saturating counter
    TAGE_UsefulBits    = 2                          // Usefulness counter
    
    // History lengths: geometric series
    // T1: 4, T2: 8, T3: 16, T4: 32, T5: 64, T6: 128
    
    // Statistical Corrector
    SC_BiasTableSize   = 512                        // Bias table entries
    SC_WeightTableSize = 512                        // Weight table entries
    SC_ThresholdBits   = 6                          // Dynamic threshold
    
    // Loop Predictor
    Loop_Entries       = 64                         // Loop table entries
    Loop_CounterBits   = 14                         // Max loop count: 16384
)

// Global history register
type GlobalHistory struct {
    Path     uint64  // 64-bit path history (branch addresses)
    Outcome  uint64  // 64-bit outcome history (taken/not-taken)
}

// TAGEEntry represents one entry in a TAGE table
type TAGEEntry struct {
    Valid   bool
    Tag     uint16    // Partial tag for filtering
    Counter int8      // 3-bit signed: -4 to +3
    Useful  uint8     // 2-bit usefulness: 0-3
}

// TAGETable represents one tagged table
type TAGETable struct {
    Entries       [TAGE_TableSize]TAGEEntry
    HistoryLength int
}

// SCEntry represents statistical corrector state
type SCEntry struct {
    Bias   int8   // Bias counter
    Weight int8   // Weight for TAGE counter
}

// LoopEntry represents one loop predictor entry
type LoopEntry struct {
    Valid          bool
    Tag            uint16
    CurrentIter    uint16   // Current iteration count
    LoopCount      uint16   // Detected loop count
    Confidence     uint8    // Times loop count confirmed
    Age            uint8    // For replacement
}

// TAGEPredictor is the complete predictor
type TAGEPredictor struct {
    // Global state
    GHR             GlobalHistory
    
    // Base predictor (bimodal)
    BaseTable       [TAGE_BaseTableSize]int8  // 2-bit counters
    
    // TAGE tables
    Tables          [TAGE_NumTables]TAGETable
    HistoryLengths  [TAGE_NumTables]int
    
    // Statistical corrector
    SCBias          [SC_BiasTableSize]int8
    SCWeight        [SC_WeightTableSize]int8
    SCThreshold     int
    
    // Loop predictor
    LoopTable       [Loop_Entries]LoopEntry
    
    // Prediction state (for update)
    LastPrediction  PredictionState
    
    Stats           PredictorStats
}

type PredictionState struct {
    PC              uint64
    BasePred        bool
    TAGEPred        bool
    TAGEProvider    int      // Which table provided prediction (-1 = base)
    TAGEAltProvider int      // Alternate provider
    SCCorrection    bool     // Did SC flip the prediction?
    LoopPred        bool
    LoopValid       bool
    FinalPred       bool
}

type PredictorStats struct {
    Predictions     uint64
    Mispredictions  uint64
    TAGEHits        [TAGE_NumTables]uint64
    SCCorrections   uint64
    LoopPredictions uint64
}

// NewTAGEPredictor creates and initializes the predictor
func NewTAGEPredictor() *TAGEPredictor {
    p := &TAGEPredictor{
        HistoryLengths: [TAGE_NumTables]int{4, 8, 16, 32, 64, 128},
        SCThreshold:    8,
    }
    
    // Initialize tables with history lengths
    for i := 0; i < TAGE_NumTables; i++ {
        p.Tables[i].HistoryLength = p.HistoryLengths[i]
    }
    
    return p
}

// hash combines PC and history for table indexing
func (p *TAGEPredictor) hash(pc uint64, history uint64, histLen int) uint64 {
    // Fold history to match table size
    folded := history
    for shift := histLen; shift < 64; shift += histLen {
        folded ^= (history >> shift)
    }
    
    // Combine with PC
    return (pc ^ (pc >> 4) ^ folded) & (TAGE_TableSize - 1)
}

// tagHash generates partial tag from PC and history
func (p *TAGEPredictor) tagHash(pc uint64, history uint64, histLen int) uint16 {
    h := pc ^ (history << 1) ^ (history >> (histLen - 1))
    return uint16(h & ((1 << TAGE_TagBits) - 1))
}

// Predict generates a prediction for a branch
func (p *TAGEPredictor) Predict(pc uint64) bool {
    p.Stats.Predictions++
    
    state := PredictionState{PC: pc, TAGEProvider: -1, TAGEAltProvider: -1}
    
    // 1. Base prediction (bimodal)
    baseIdx := (pc >> 2) & (TAGE_BaseTableSize - 1)
    state.BasePred = p.BaseTable[baseIdx] >= 0
    
    // 2. TAGE prediction - find longest matching history
    for t := TAGE_NumTables - 1; t >= 0; t-- {
        idx := p.hash(pc, p.GHR.Outcome, p.HistoryLengths[t])
        tag := p.tagHash(pc, p.GHR.Outcome, p.HistoryLengths[t])
        
        entry := &p.Tables[t].Entries[idx]
        if entry.Valid && entry.Tag == tag {
            p.Stats.TAGEHits[t]++
            
            if state.TAGEProvider == -1 {
                state.TAGEProvider = t
                state.TAGEPred = entry.Counter >= 0
            } else if state.TAGEAltProvider == -1 {
                state.TAGEAltProvider = t
            }
        }
    }
    
    // Use TAGE if we have a match, otherwise base
    prediction := state.BasePred
    if state.TAGEProvider >= 0 {
        prediction = state.TAGEPred
    }
    
    // 3. Statistical Corrector
    scIdx := (pc ^ p.GHR.Outcome) & (SC_BiasTableSize - 1)
    scSum := int(p.SCBias[scIdx])
    
    if state.TAGEProvider >= 0 {
        weightIdx := (pc ^ uint64(state.TAGEProvider)) & (SC_WeightTableSize - 1)
        providerEntry := &p.Tables[state.TAGEProvider].Entries[p.hash(pc, p.GHR.Outcome, p.HistoryLengths[state.TAGEProvider])]
        scSum += int(p.SCWeight[weightIdx]) * int(providerEntry.Counter)
    }
    
    // SC correction
    if abs(scSum) > p.SCThreshold {
        if (scSum >= 0) != prediction {
            prediction = scSum >= 0
            state.SCCorrection = true
        }
    }
    
    // 4. Loop Predictor (overrides if confident)
    loopIdx := (pc >> 2) & (Loop_Entries - 1)
    loopEntry := &p.LoopTable[loopIdx]
    loopTag := uint16((pc >> 8) & 0xFFFF)
    
    if loopEntry.Valid && loopEntry.Tag == loopTag && loopEntry.Confidence >= 3 {
        state.LoopValid = true
        state.LoopPred = loopEntry.CurrentIter < loopEntry.LoopCount
        prediction = state.LoopPred
        p.Stats.LoopPredictions++
    }
    
    state.FinalPred = prediction
    p.LastPrediction = state
    
    return prediction
}

// Update updates predictor state after branch resolution
func (p *TAGEPredictor) Update(pc uint64, taken bool, target uint64) {
    state := p.LastPrediction
    
    // Track mispredictions
    if state.FinalPred != taken {
        p.Stats.Mispredictions++
    }
    
    // 1. Update base predictor
    baseIdx := (pc >> 2) & (TAGE_BaseTableSize - 1)
    if taken {
        if p.BaseTable[baseIdx] < 3 {
            p.BaseTable[baseIdx]++
        }
    } else {
        if p.BaseTable[baseIdx] > -4 {
            p.BaseTable[baseIdx]--
        }
    }
    
    // 2. Update TAGE tables
    if state.TAGEProvider >= 0 {
        idx := p.hash(pc, p.GHR.Outcome, p.HistoryLengths[state.TAGEProvider])
        entry := &p.Tables[state.TAGEProvider].Entries[idx]
        
        // Update counter
        if taken {
            if entry.Counter < 3 {
                entry.Counter++
            }
        } else {
            if entry.Counter > -4 {
                entry.Counter--
            }
        }
        
        // Update usefulness
        if state.TAGEPred != state.BasePred {
            if state.TAGEPred == taken {
                if entry.Useful < 3 {
                    entry.Useful++
                }
            } else {
                if entry.Useful > 0 {
                    entry.Useful--
                }
            }
        }
    }
    
    // Allocate new entry on misprediction
    if state.FinalPred != taken && state.TAGEProvider < TAGE_NumTables-1 {
        // Try to allocate in a longer-history table
        for t := state.TAGEProvider + 1; t < TAGE_NumTables; t++ {
            idx := p.hash(pc, p.GHR.Outcome, p.HistoryLengths[t])
            entry := &p.Tables[t].Entries[idx]
            
            if !entry.Valid || entry.Useful == 0 {
                entry.Valid = true
                entry.Tag = p.tagHash(pc, p.GHR.Outcome, p.HistoryLengths[t])
                entry.Counter = 0
                if taken {
                    entry.Counter = 1
                } else {
                    entry.Counter = -1
                }
                entry.Useful = 0
                break
            }
        }
    }
    
    // 3. Update Statistical Corrector
    scIdx := (pc ^ p.GHR.Outcome) & (SC_BiasTableSize - 1)
    if taken {
        if p.SCBias[scIdx] < 31 {
            p.SCBias[scIdx]++
        }
    } else {
        if p.SCBias[scIdx] > -32 {
            p.SCBias[scIdx]--
        }
    }
    
    // Update SC threshold dynamically
    if state.SCCorrection {
        if state.FinalPred == taken {
            p.SCThreshold--
        } else {
            p.SCThreshold++
        }
        if p.SCThreshold < 4 {
            p.SCThreshold = 4
        }
        if p.SCThreshold > 16 {
            p.SCThreshold = 16
        }
        p.Stats.SCCorrections++
    }
    
    // 4. Update Loop Predictor
    loopIdx := (pc >> 2) & (Loop_Entries - 1)
    loopEntry := &p.LoopTable[loopIdx]
    loopTag := uint16((pc >> 8) & 0xFFFF)
    
    if loopEntry.Valid && loopEntry.Tag == loopTag {
        if taken {
            loopEntry.CurrentIter++
        } else {
            // Loop exit - check if we predicted correctly
            if loopEntry.CurrentIter == loopEntry.LoopCount {
                if loopEntry.Confidence < 7 {
                    loopEntry.Confidence++
                }
            } else {
                // Wrong count - relearn
                loopEntry.LoopCount = loopEntry.CurrentIter
                loopEntry.Confidence = 0
            }
            loopEntry.CurrentIter = 0
        }
    } else if !taken {
        // Potential new loop - allocate entry
        loopEntry.Valid = true
        loopEntry.Tag = loopTag
        loopEntry.CurrentIter = 0
        loopEntry.LoopCount = 0
        loopEntry.Confidence = 0
    }
    
    // 5. Update global history
    p.GHR.Outcome = (p.GHR.Outcome << 1) | boolToUint64(taken)
    p.GHR.Path = (p.GHR.Path << 4) ^ (pc >> 2)
}

func boolToUint64(b bool) uint64 {
    if b {
        return 1
    }
    return 0
}

func abs(x int) int {
    if x < 0 {
        return -x
    }
    return x
}

// GetAccuracy returns the prediction accuracy
func (p *TAGEPredictor) GetAccuracy() float64 {
    if p.Stats.Predictions == 0 {
        return 0
    }
    return 1.0 - float64(p.Stats.Mispredictions)/float64(p.Stats.Predictions)
}

package suprax

// =============================================================================
// BRANCH TARGET BUFFER - Cycle-Accurate Model
// =============================================================================

const (
    BTB_Entries     = 4096
    BTB_Ways        = 4
    BTB_Sets        = BTB_Entries / BTB_Ways  // 1024 sets
    BTB_TagBits     = 20
    BTB_TargetBits  = 48   // Sufficient for 256TB address space
)

// BranchType classifies branches for special handling
type BranchType uint8

const (
    BranchDirect   BranchType = iota  // Conditional direct branch
    BranchJump                        // Unconditional direct jump
    BranchCall                        // Function call (push RAS)
    BranchReturn                      // Function return (pop RAS)
    BranchIndirect                    // Indirect branch (computed target)
)

// BTBEntry represents one BTB entry
type BTBEntry struct {
    Valid      bool
    Tag        uint32      // Partial PC tag
    Target     uint64      // Predicted target address
    BranchType BranchType  // Type for RAS/indirect handling
    Hysteresis uint8       // 2-bit confidence counter
}

// BTBSet represents one set (4 ways)
type BTBSet struct {
    Entries [BTB_Ways]BTBEntry
    PLRU    uint8  // 3-bit pseudo-LRU
}

// BTB is the complete branch target buffer
type BTB struct {
    Sets  [BTB_Sets]BTBSet
    Stats BTBStats
}

type BTBStats struct {
    Lookups      uint64
    Hits         uint64
    Misses       uint64
    TypeHits     [5]uint64  // Per branch type
}

// NewBTB creates a new BTB
func NewBTB() *BTB {
    return &BTB{}
}

// addressToSetAndTag extracts set index and tag from PC
func (btb *BTB) addressToSetAndTag(pc uint64) (set int, tag uint32) {
    // PC[13:4] for set (1024 sets, ignore bottom 4 bits for bundle alignment)
    set = int((pc >> 4) & (BTB_Sets - 1))
    // PC[33:14] for tag (20 bits)
    tag = uint32((pc >> 14) & ((1 << BTB_TagBits) - 1))
    return
}

// Lookup queries the BTB for a branch target
// Returns: target, branch type, hit status
func (btb *BTB) Lookup(pc uint64) (target uint64, brType BranchType, hit bool) {
    btb.Stats.Lookups++
    
    setIdx, tag := btb.addressToSetAndTag(pc)
    set := &btb.Sets[setIdx]
    
    // Check all ways in parallel (hardware does this simultaneously)
    for way := 0; way < BTB_Ways; way++ {
        entry := &set.Entries[way]
        if entry.Valid && entry.Tag == tag {
            btb.Stats.Hits++
            btb.Stats.TypeHits[entry.BranchType]++
            btb.updatePLRU(set, way)
            return entry.Target, entry.BranchType, true
        }
    }
    
    btb.Stats.Misses++
    return 0, BranchDirect, false
}

// Update updates or allocates a BTB entry
func (btb *BTB) Update(pc uint64, target uint64, brType BranchType, taken bool) {
    setIdx, tag := btb.addressToSetAndTag(pc)
    set := &btb.Sets[setIdx]
    
    // Look for existing entry
    for way := 0; way < BTB_Ways; way++ {
        entry := &set.Entries[way]
        if entry.Valid && entry.Tag == tag {
            // Update existing entry
            if taken {
                entry.Target = target
                entry.BranchType = brType
                if entry.Hysteresis < 3 {
                    entry.Hysteresis++
                }
            } else {
                if entry.Hysteresis > 0 {
                    entry.Hysteresis--
                }
                // Remove entry if confidence drops to zero
                if entry.Hysteresis == 0 {
                    entry.Valid = false
                }
            }
            btb.updatePLRU(set, way)
            return
        }
    }
    
    // Allocate new entry only for taken branches
    if !taken {
        return
    }
    
    // Find victim using PLRU
    victimWay := btb.getPLRUVictim(set)
    entry := &set.Entries[victimWay]
    
    entry.Valid = true
    entry.Tag = tag
    entry.Target = target
    entry.BranchType = brType
    entry.Hysteresis = 2  // Start with moderate confidence
    
    btb.updatePLRU(set, victimWay)
}

// updatePLRU updates pseudo-LRU bits (same as I-cache)
func (btb *BTB) updatePLRU(set *BTBSet, accessedWay int) {
    switch accessedWay {
    case 0:
        set.PLRU = (set.PLRU | 0x4) | 0x2
    case 1:
        set.PLRU = (set.PLRU | 0x4) & ^uint8(0x2)
    case 2:
        set.PLRU = (set.PLRU & ^uint8(0x4)) | 0x1
    case 3:
        set.PLRU = (set.PLRU & ^uint8(0x4)) & ^uint8(0x1)
    }
}

// getPLRUVictim returns the PLRU way for replacement
func (btb *BTB) getPLRUVictim(set *BTBSet) int {
    // First check for invalid entries
    for way := 0; way < BTB_Ways; way++ {
        if !set.Entries[way].Valid {
            return way
        }
    }
    
    // Use PLRU
    if set.PLRU&0x4 == 0 {
        if set.PLRU&0x2 == 0 {
            return 0
        }
        return 1
    }
    if set.PLRU&0x1 == 0 {
        return 2
    }
    return 3
}

// GetHitRate returns BTB hit rate
func (btb *BTB) GetHitRate() float64 {
    if btb.Stats.Lookups == 0 {
        return 0
    }
    return float64(btb.Stats.Hits) / float64(btb.Stats.Lookups)
}

package suprax

// =============================================================================
// RETURN ADDRESS STACK - Cycle-Accurate Model
// =============================================================================

const (
    RAS_Depth           = 48
    RAS_CheckpointSlots = 8  // Match RAT checkpoints
)

// RASEntry represents one return address entry
type RASEntry struct {
    ReturnAddress uint64
    CallSitePC    uint64  // For debugging/validation
    Valid         bool
}

// RASCheckpoint stores RAS state for recovery
type RASCheckpoint struct {
    Valid         bool
    SpecTop       int
    CheckpointID  int
}

// RAS is the complete return address stack
type RAS struct {
    Stack         [RAS_Depth]RASEntry
    
    // Pointers
    SpecTop       int  // Speculative top of stack (prediction uses this)
    CommitTop     int  // Committed top (updated at retirement)
    
    // Checkpoints for branch recovery
    Checkpoints   [RAS_CheckpointSlots]RASCheckpoint
    NextCheckpoint int
    
    Stats         RASStats
}

type RASStats struct {
    Pushes        uint64
    Pops          uint64
    Recoveries    uint64
    Overflows     uint64  // When stack wraps
}

// NewRAS creates a new RAS
func NewRAS() *RAS {
    return &RAS{
        SpecTop:   -1,  // Empty stack
        CommitTop: -1,
    }
}

// Push pushes a return address (called on CALL prediction)
func (ras *RAS) Push(returnAddr uint64, callSitePC uint64) {
    ras.Stats.Pushes++
    
    // Increment speculative pointer (circular)
    ras.SpecTop = (ras.SpecTop + 1) % RAS_Depth
    
    // Check for overflow (wrapping)
    if ras.SpecTop == ras.CommitTop {
        ras.Stats.Overflows++
        // Oldest entry is overwritten - this is expected behavior
    }
    
    ras.Stack[ras.SpecTop] = RASEntry{
        ReturnAddress: returnAddr,
        CallSitePC:    callSitePC,
        Valid:         true,
    }
}

// Pop returns predicted return address (called on RETURN prediction)
func (ras *RAS) Pop() (addr uint64, valid bool) {
    if ras.SpecTop < 0 || !ras.Stack[ras.SpecTop].Valid {
        return 0, false  // Empty or invalid - use BTB
    }
    
    ras.Stats.Pops++
    
    addr = ras.Stack[ras.SpecTop].ReturnAddress
    ras.Stack[ras.SpecTop].Valid = false
    
    // Decrement speculative pointer
    ras.SpecTop--
    if ras.SpecTop < 0 {
        ras.SpecTop = RAS_Depth - 1  // Wrap
    }
    
    return addr, true
}

// Peek returns TOS without modifying stack (for validation)
func (ras *RAS) Peek() (addr uint64, valid bool) {
    if ras.SpecTop < 0 || !ras.Stack[ras.SpecTop].Valid {
        return 0, false
    }
    return ras.Stack[ras.SpecTop].ReturnAddress, true
}

// CreateCheckpoint saves current RAS state for branch recovery
func (ras *RAS) CreateCheckpoint() int {
    slot := ras.NextCheckpoint
    ras.NextCheckpoint = (ras.NextCheckpoint + 1) % RAS_CheckpointSlots
    
    ras.Checkpoints[slot] = RASCheckpoint{
        Valid:        true,
        SpecTop:      ras.SpecTop,
        CheckpointID: slot,
    }
    
    return slot
}

// RestoreCheckpoint restores RAS state on misprediction
func (ras *RAS) RestoreCheckpoint(slot int) bool {
    if slot < 0 || slot >= RAS_CheckpointSlots {
        return false
    }
    
    checkpoint := &ras.Checkpoints[slot]
    if !checkpoint.Valid {
        return false
    }
    
    ras.Stats.Recoveries++
    
    // Restore speculative pointer
    // Note: actual stack contents are unchanged - we just move the pointer
    ras.SpecTop = checkpoint.SpecTop
    
    // Invalidate this and all newer checkpoints
    ras.invalidateCheckpointsFrom(slot)
    
    return true
}

// invalidateCheckpointsFrom invalidates checkpoints from slot onward
func (ras *RAS) invalidateCheckpointsFrom(slot int) {
    // Invalidate all checkpoints that were created after this one
    // (they're on the wrong speculative path)
    ras.Checkpoints[slot].Valid = false
    
    for i := 0; i < RAS_CheckpointSlots; i++ {
        if i == slot {
            continue
        }
        // Use checkpoint ID ordering to determine "newer"
        // This is simplified - real implementation tracks epoch
        if ras.Checkpoints[i].CheckpointID > slot {
            ras.Checkpoints[i].Valid = false
        }
    }
}

// CommitCall commits a call (called when CALL instruction retires)
func (ras *RAS) CommitCall() {
    // Advance committed pointer
    ras.CommitTop = (ras.CommitTop + 1) % RAS_Depth
}

// CommitReturn commits a return (called when RETURN instruction retires)
func (ras *RAS) CommitReturn() {
    // Move committed pointer back
    ras.CommitTop--
    if ras.CommitTop < 0 {
        ras.CommitTop = RAS_Depth - 1
    }
}

// GetDepth returns current speculative stack depth
func (ras *RAS) GetDepth() int {
    if ras.SpecTop < 0 {
        return 0
    }
    
    depth := ras.SpecTop - ras.CommitTop
    if depth < 0 {
        depth += RAS_Depth
    }
    return depth
}

package suprax

// =============================================================================
// FETCH UNIT & BUNDLE QUEUE - Cycle-Accurate Model
// =============================================================================

const (
    FetchWidth       = 12    // Bundles fetched per cycle
    BundleQueueDepth = 64    // Bundle queue capacity
    BundleSize       = 16    // Bytes per bundle (128 bits)
    BytesPerFetch    = FetchWidth * BundleSize  // 192 bytes
)

// Bundle represents a 128-bit instruction bundle
type Bundle struct {
    Valid     bool
    PC        uint64
    RawBytes  [BundleSize]byte
    
    // Decoded info (filled by pre-decode)
    Format    BundleFormat
    NumOps    int
    IsBranch  bool
    BranchPC  uint64  // If contains branch, which op
}

type BundleFormat uint8

const (
    FormatNOP       BundleFormat = iota  // All NOPs
    FormatQuad                           // 4 regular operations
    FormatBroadcast                      // Broadcast operation
    FormatPartial                        // <4 operations (tail of basic block)
)

// BundleQueueEntry is one slot in the bundle queue
type BundleQueueEntry struct {
    Bundle    Bundle
    Predicted bool    // Was this fetched speculatively?
    EpochID   uint64  // For flush on mispredict
}

// BundleQueue is the circular bundle queue
type BundleQueue struct {
    Entries   [BundleQueueDepth]BundleQueueEntry
    Head      int     // Next to dequeue
    Tail      int     // Next to enqueue
    Count     int     // Current occupancy
    EpochID   uint64  // Incremented on flush
}

// FetchUnit manages instruction fetch
type FetchUnit struct {
    // Current fetch state
    PC            uint64
    NextPC        uint64
    Stalled       bool
    StallReason   string
    
    // Connections to other components
    ICache        *L1ICache
    BranchPred    *TAGEPredictor
    BTB           *BTB
    RAS           *RAS
    
    // Output queue
    Queue         BundleQueue
    
    // Pipeline registers
    Stage1_PC     uint64
    Stage1_Valid  bool
    Stage2_Data   [BytesPerFetch]byte
    Stage2_Valid  bool
    Stage2_PC     uint64
    
    Stats         FetchStats
}

type FetchStats struct {
    CyclesFetching uint64
    CyclesStalled  uint64
    BundlesFetched uint64
    BundlesDropped uint64  // On flush
    BranchRedirects uint64
}

// NewFetchUnit creates a new fetch unit
func NewFetchUnit(icache *L1ICache, bp *TAGEPredictor, btb *BTB, ras *RAS) *FetchUnit {
    return &FetchUnit{
        ICache:     icache,
        BranchPred: bp,
        BTB:        btb,
        RAS:        ras,
    }
}

// Cycle performs one cycle of fetch
func (fu *FetchUnit) Cycle() {
    // Check if queue has space
    if fu.Queue.Count >= BundleQueueDepth-FetchWidth {
        fu.Stalled = true
        fu.StallReason = "queue full"
        fu.Stats.CyclesStalled++
        return
    }
    
    fu.Stats.CyclesFetching++
    
    // Stage 1: Initiate I-cache access
    fu.Stage1_PC = fu.PC
    fu.Stage1_Valid = true
    
    // Stage 2: Process previous cycle's fetch
    if fu.Stage2_Valid {
        fu.processFetchedBundles()
    }
    
    // Access I-cache
    data, hit, latency := fu.ICache.Access(fu.PC)
    
    if hit {
        if latency == 1 {
            // Fast path: process immediately
            copy(fu.Stage2_Data[:], data[:BytesPerFetch])
            fu.Stage2_Valid = true
            fu.Stage2_PC = fu.PC
        } else {
            // Way misprediction: available next cycle
            fu.Stage2_Valid = false
        }
        
        // Advance PC to next fetch group
        fu.advancePC()
    } else {
        // I-cache miss - stall
        fu.Stalled = true
        fu.StallReason = "icache miss"
        fu.Stats.CyclesStalled++
    }
}

// processFetchedBundles processes fetched data into bundles
func (fu *FetchUnit) processFetchedBundles() {
    pc := fu.Stage2_PC
    
    for i := 0; i < FetchWidth; i++ {
        // Extract bundle bytes
        bundleOffset := i * BundleSize
        var bundleBytes [BundleSize]byte
        copy(bundleBytes[:], fu.Stage2_Data[bundleOffset:bundleOffset+BundleSize])
        
        // Pre-decode bundle
        bundle := fu.preDecodeBundle(bundleBytes, pc)
        bundle.PC = pc
        
        // Enqueue bundle
        fu.Queue.Enqueue(bundle, fu.Queue.EpochID)
        fu.Stats.BundlesFetched++
        
        // Check for branch
        if bundle.IsBranch {
            fu.handleBranchInBundle(bundle)
            // Stop fetching at branch (basic block boundary)
            break
        }
        
        pc += BundleSize
    }
}

// preDecodeBundle performs minimal decode for format detection
func (fu *FetchUnit) preDecodeBundle(bytes [BundleSize]byte, pc uint64) Bundle {
    bundle := Bundle{
        Valid:    true,
        RawBytes: bytes,
    }
    
    // Check for NOP bundle (all zeros in opcode fields)
    opcodes := uint32(bytes[0]) | uint32(bytes[1])<<8 | 
               uint32(bytes[2])<<16 | uint32(bytes[3])<<24
    
    if opcodes == 0 {
        bundle.Format = FormatNOP
        bundle.NumOps = 0
        return bundle
    }
    
    // Check format indicator (top 2 bits of first byte)
    formatBits := bytes[0] >> 6
    
    switch formatBits {
    case 0, 1:  // Standard quad format
        bundle.Format = FormatQuad
        bundle.NumOps = 4
    case 2:  // Broadcast format
        bundle.Format = FormatBroadcast
        bundle.NumOps = 1  // Single broadcast op
    case 3:  // Reserved/partial
        bundle.Format = FormatPartial
        bundle.NumOps = int(bytes[0] & 0x3)  // Bottom 2 bits = op count
    }
    
    // Check for branch (simplified - real decode checks opcode)
    // Assume branch opcode is in range 0x30-0x3F
    for op := 0; op < bundle.NumOps; op++ {
        opcode := bytes[op]
        if opcode >= 0x30 && opcode <= 0x3F {
            bundle.IsBranch = true
            bundle.BranchPC = pc + uint64(op*4)  // Approximate
            break
        }
    }
    
    return bundle
}

// handleBranchInBundle handles branch prediction for a bundle
func (fu *FetchUnit) handleBranchInBundle(bundle Bundle) {
    // Get branch prediction
    taken := fu.BranchPred.Predict(bundle.BranchPC)
    
    if taken {
        // Get target from BTB
        target, brType, hit := fu.BTB.Lookup(bundle.BranchPC)
        
        if brType == BranchReturn {
            // Use RAS for return prediction
            rasTarget, rasValid := fu.RAS.Pop()
            if rasValid {
                target = rasTarget
                hit = true
            }
        } else if brType == BranchCall {
            // Push return address to RAS
            returnAddr := bundle.BranchPC + 4  // Next instruction
            fu.RAS.Push(returnAddr, bundle.BranchPC)
        }
        
        if hit {
            fu.NextPC = target
            fu.Stats.BranchRedirects++
        }
    }
}

// advancePC advances fetch PC, checking for branch redirects
func (fu *FetchUnit) advancePC() {
    if fu.NextPC != 0 && fu.NextPC != fu.PC+BytesPerFetch {
        // Branch redirect
        fu.PC = fu.NextPC
        fu.NextPC = 0
    } else {
        // Sequential
        fu.PC = fu.PC + BytesPerFetch
    }
}

// Flush flushes the fetch unit on misprediction
func (fu *FetchUnit) Flush(correctPC uint64) {
    fu.PC = correctPC
    fu.NextPC = 0
    fu.Stage1_Valid = false
    fu.Stage2_Valid = false
    fu.Stalled = false
    
    // Clear queue
    dropped := fu.Queue.Flush()
    fu.Stats.BundlesDropped += uint64(dropped)
}

// Dequeue removes bundles for decode stage
func (fu *FetchUnit) Dequeue(count int) []Bundle {
    return fu.Queue.Dequeue(count)
}

// --- Bundle Queue Methods ---

// Enqueue adds a bundle to the queue
func (q *BundleQueue) Enqueue(bundle Bundle, epochID uint64) bool {
    if q.Count >= BundleQueueDepth {
        return false  // Queue full
    }
    
    q.Entries[q.Tail] = BundleQueueEntry{
        Bundle:    bundle,
        Predicted: true,
        EpochID:   epochID,
    }
    
    q.Tail = (q.Tail + 1) % BundleQueueDepth
    q.Count++
    return true
}

// Dequeue removes bundles from the queue
func (q *BundleQueue) Dequeue(count int) []Bundle {
    if count > q.Count {
        count = q.Count
    }
    
    bundles := make([]Bundle, count)
    for i := 0; i < count; i++ {
        bundles[i] = q.Entries[q.Head].Bundle
        q.Head = (q.Head + 1) % BundleQueueDepth
    }
    q.Count -= count
    
    return bundles
}

// Flush clears the queue on misprediction
func (q *BundleQueue) Flush() int {
    dropped := q.Count
    q.Head = 0
    q.Tail = 0
    q.Count = 0
    q.EpochID++
    return dropped
}

// Occupancy returns current queue fill level
func (q *BundleQueue) Occupancy() float64 {
    return float64(q.Count) / float64(BundleQueueDepth)
}